#!/usr/bin/env python3
"""
Usage examples for the Codebase RAG MCP Server

This file demonstrates how to use the MCP tools provided by the server.
These examples would be executed by MCP clients like Claude Desktop.
"""

# Example 1: Verify Configuration
"""
Tool: verify_configuration
Parameters: {}

Expected Response: Configuration status and any setup issues
"""

# Example 2: Index a Codebase
"""
Tool: index_codebase
Parameters: {
    "directory": "/path/to/your/project"
}

Expected Response: Indexing progress and statistics
"""

# Example 3: Search for Code
"""
Tool: search_code
Parameters: {
    "query": "function that handles user authentication",
    "max_results": 5,
    "min_score": 0.8
}

Expected Response: Relevant code snippets with similarity scores
"""

# Example 4: Search in Specific Directory
"""
Tool: search_code
Parameters: {
    "query": "database connection logic",
    "directory_prefix": "src/database",
    "max_results": 3
}

Expected Response: Code results filtered to the database directory
"""

# Example 5: Check Index Status
"""
Tool: get_index_status
Parameters: {}

Expected Response: Current indexing state, statistics, and guidance
"""

# Example 6: Clear Index (with confirmation)
"""
Tool: clear_index
Parameters: {
    "confirm": true
}

Expected Response: Confirmation of successful index clearing
"""

# Sample MCP Client Integration for Claude Desktop
CLAUDE_DESKTOP_CONFIG = """
{
  "mcpServers": {
    "codebase-rag": {
      "command": "sh",
      "args": ["/path/to/codebase-rag-mcp/run.sh"],
      "env": {
        "EMBEDDER_PROVIDER": "openai",
        "OPENAI_API_KEY": "your-openai-api-key",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}
"""

# Sample Usage Flow
TYPICAL_WORKFLOW = """
1. Start Qdrant vector database:
   docker run -p 6333:6333 qdrant/qdrant

2. Configure environment variables in Claude Desktop or .env file

3. Verify configuration:
   - Use verify_configuration tool

4. Index your codebase:
   - Use index_codebase tool with your project directory

5. Search for code:
   - Use search_code tool with natural language queries
   - Experiment with different min_score thresholds
   - Use directory_prefix to narrow search scope

6. Monitor and manage:
   - Use get_index_status to check system state
   - Use clear_index when needed to reset

7. Real-time updates:
   - File watching automatically keeps index current
   - No manual re-indexing needed for file changes
"""

# Common Search Query Examples
SEARCH_EXAMPLES = [
    "functions that handle HTTP requests",
    "code that connects to database",
    "user authentication logic",
    "error handling patterns",
    "API endpoint definitions",
    "configuration file parsing",
    "data validation functions",
    "logging and monitoring code",
    "unit test examples",
    "Docker configuration files",
]

# Troubleshooting Common Issues
TROUBLESHOOTING = """
1. "Embedder configuration error":
   - Check your API keys
   - Verify the embedding service is accessible
   - Ensure correct EMBEDDER_PROVIDER value

2. "Vector database connection failed":
   - Start Qdrant: docker run -p 6333:6333 qdrant/qdrant
   - Check QDRANT_URL configuration
   - Verify network connectivity

3. "No results found":
   - Check if codebase was indexed successfully
   - Try broader search terms
   - Lower the min_score threshold
   - Verify the directory contains supported file types

4. "Rate limit exceeded":
   - The system automatically retries with backoff
   - Consider using Ollama for unlimited local processing
   - Check your API usage limits

5. "Permission denied":
   - Ensure read access to the directory
   - Check file system permissions
   - Verify the directory path is correct
"""
